
/*
 * Copyright 2002-2022 the original author or authors.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      https://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
/*
 *版权所有2002-2022原作者。
 *
 *根据Apache许可证2.0版（“许可证”）获得许可；
 *除非符合许可证，否则不得使用此文件。
 *您可以在以下地址获取许可证副本：
 *
 *      https://www.apache.org/licenses/LICENSE-2.0
 *
 *除非适用法律要求或书面同意，软件
 *根据许可证分发的内容是按“原样”分发的，
 *无任何明示或暗示的保证或条件。
 *有关管理权限和
 *许可证下的限制。
 */

package org.springframework.beans.factory.config;

import java.io.IOException;
import java.util.Enumeration;
import java.util.Properties;

import org.springframework.beans.BeansException;
import org.springframework.beans.factory.BeanInitializationException;
import org.springframework.core.Ordered;
import org.springframework.core.PriorityOrdered;
import org.springframework.core.io.support.PropertiesLoaderSupport;
import org.springframework.util.ObjectUtils;

/**
 * Allows for configuration of individual bean property values from a property resource,
 * i.e. a properties file. Useful for custom config files targeted at system
 * administrators that override bean properties configured in the application context.
 *
 * <p>Two concrete implementations are provided in the distribution:
 * <ul>
 * <li>{@link PropertyOverrideConfigurer} for "beanName.property=value" style overriding
 * (<i>pushing</i> values from a properties file into bean definitions)
 * <li>{@link PropertyPlaceholderConfigurer} for replacing "${...}" placeholders
 * (<i>pulling</i> values from a properties file into bean definitions)
 * </ul>
 *
 * <p>Property values can be converted after reading them in, through overriding
 * the {@link #convertPropertyValue} method. For example, encrypted values
 * can be detected and decrypted accordingly before processing them.
 *
 * @author Juergen Hoeller
 * @since 02.10.2003
 * @see PropertyOverrideConfigurer
 * @see PropertyPlaceholderConfigurer
 */
/**
 *允许从属性资源配置单个bean属性值，
 *即财产文件。适用于以系统为目标的自定义配置文件
 *覆盖应用程序上下文中配置的bean财产的管理员。
 *
 *＜p＞发行版中提供了两个具体的实现：
 *＜ul＞
 *＜li＞｛@link PropertyOverrideConfigurer｝用于“beanName.properties=value”样式重写
 *（将值从财产文件推送到bean定义中）
 *<li>｛@link PropertyPlaceholderConfigurator｝用于替换“$｛…｝”占位符
 *（将值从财产文件拉入bean定义）
 *</ul>
 *
 *＜p＞属性值可以在读入后通过重写进行转换
 *｛@link#convertPropertyValue｝方法。例如，加密值
 *可以在处理它们之前相应地检测和解密。
 *
 *@作者Juergen Hoeller
 *@自2003年10月2日
 *@参见PropertyOverrideConfigurer
 *@参见PropertyPlaceholderConfigurator
 */
public abstract class PropertyResourceConfigurer extends PropertiesLoaderSupport
		implements BeanFactoryPostProcessor, PriorityOrdered {

	private int order = Ordered.LOWEST_PRECEDENCE;  // default: same as non-Ordered


	/**
	 * Set the order value of this object for sorting purposes.
	 * @see PriorityOrdered
	 */
	/**
	 *设置此对象的顺序值以进行排序。
	 *@参见PriorityOrdered
	 */
	public void setOrder(int order) {
		this.order = order;
	}

	@Override
	public int getOrder() {
		return this.order;
	}


	/**
	 * {@linkplain #mergeProperties Merge}, {@linkplain #convertProperties convert} and
	 * {@linkplain #processProperties process} properties against the given bean factory.
	 * @throws BeanInitializationException if any properties cannot be loaded
	 */
	/**
	 *｛@linkplain#mergeProperties Merge｝、｛@linkplain#convertProperties convert｝和
	 *{@linkplain#processProperties process}针对给定bean工厂的财产。
	 *@throws BeanInitializationException（如果无法加载任何财产）
	 */
	@Override
	public void postProcessBeanFactory(ConfigurableListableBeanFactory beanFactory) throws BeansException {
		try {
			Properties mergedProps = mergeProperties();

			// Convert the merged properties, if necessary.
			// 如有必要，转换合并的财产。
			convertProperties(mergedProps);

			// Let the subclass process the properties.
			// 让子类处理财产。
			processProperties(beanFactory, mergedProps);
		}
		catch (IOException ex) {
			throw new BeanInitializationException("Could not load properties: " + ex.getMessage(), ex);
		}
	}

	/**
	 * Convert the given merged properties, converting property values
	 * if necessary. The result will then be processed.
	 * <p>The default implementation will invoke {@link #convertPropertyValue}
	 * for each property value, replacing the original with the converted value.
	 * @param props the Properties to convert
	 * @see #processProperties
	 */
	/**
	 *转换给定的合并财产，转换属性值
	 *如有必要。然后将处理结果。
	 *＜p＞默认实现将调用｛@link#convertPropertyValue｝
	 *对于每个属性值，用转换后的值替换原始值。
	 *@param支持要转换的财产
	 *@参见#processProperties
	 */
	protected void convertProperties(Properties props) {
		Enumeration<?> propertyNames = props.propertyNames();
		while (propertyNames.hasMoreElements()) {
			String propertyName = (String) propertyNames.nextElement();
			String propertyValue = props.getProperty(propertyName);
			String convertedValue = convertProperty(propertyName, propertyValue);
			if (!ObjectUtils.nullSafeEquals(propertyValue, convertedValue)) {
				props.setProperty(propertyName, convertedValue);
			}
		}
	}

	/**
	 * Convert the given property from the properties source to the value
	 * which should be applied.
	 * <p>The default implementation calls {@link #convertPropertyValue(String)}.
	 * @param propertyName the name of the property that the value is defined for
	 * @param propertyValue the original value from the properties source
	 * @return the converted value, to be used for processing
	 * @see #convertPropertyValue(String)
	 */
	/**
	 *将给定属性从财产源转换为值
	 *这应该被应用。
	 *＜p＞默认实现调用｛@link#convertPropertyValue（String）｝。
	 *@param propertyName为其定义值的属性的名称
	 *@param propertyValue来自财产源的原始值
	 *@返回转换后的值，用于处理
	 *@see#convertPropertyValue（字符串）
	 */
	protected String convertProperty(String propertyName, String propertyValue) {
		return convertPropertyValue(propertyValue);
	}

	/**
	 * Convert the given property value from the properties source to the value
	 * which should be applied.
	 * <p>The default implementation simply returns the original value.
	 * Can be overridden in subclasses, for example to detect
	 * encrypted values and decrypt them accordingly.
	 * @param originalValue the original value from the properties source
	 * (properties file or local "properties")
	 * @return the converted value, to be used for processing
	 * @see #setProperties
	 * @see #setLocations
	 * @see #setLocation
	 * @see #convertProperty(String, String)
	 */
	/**
	 *将给定属性值从财产源转换为值
	 *这应该被应用。
	 *＜p＞默认实现只返回原始值。
	 *可以在子类中重写，例如检测
	 *并相应地对其进行解密。
	 *@param originalValue来自财产源的原始值
	 *（财产文件或本地“财产”）
	 *@返回转换后的值，用于处理
	 *@参见#setProperties
	 *@参见#setLocations
	 *@参见#setLocation
	 *@see#convertProperty（字符串，字符串）
	 */
	protected String convertPropertyValue(String originalValue) {
		return originalValue;
	}


	/**
	 * Apply the given Properties to the given BeanFactory.
	 * @param beanFactory the BeanFactory used by the application context
	 * @param props the Properties to apply
	 * @throws org.springframework.beans.BeansException in case of errors
	 */
	/**
	 *将给定的财产应用于给定的BeanFactory。
	 *@param beanFactory应用程序上下文使用的beanFactory
	 *@param支持要应用的财产
	 *出现错误时@throws org.springframework.beans.BeansException
	 */
	protected abstract void processProperties(ConfigurableListableBeanFactory beanFactory, Properties props)
			throws BeansException;

}
